Next: Display Action Functions, Previous: Switching Buffers, Up: Windows [Contents][Index]
The command display-buffer flexibly chooses a
window for display, and displays a specified buffer in that
window. It can be called interactively, via the key binding
C-x 4 C-o. It is also used as a subroutine by many
functions and commands, including switch-to-buffer
and pop-to-buffer (see Switching
Buffers).
This command performs several complex steps to find a window
to display in. These steps are described by means of display
actions, which have the form (function .
alist). Here, function is either a
function or a list of functions, which we refer to as action
functions; alist is an association list, which we
refer to as an action alist.
An action function accepts two arguments: the buffer to
display and an action alist. It attempts to display the buffer in
some window, picking or creating a window according to its own
criteria. If successful, it returns the window; otherwise, it
returns nil. See Display
Action Functions, for a list of predefined action
functions.
display-buffer works by combining display actions
from several sources, and calling the action functions in turn,
until one of them manages to display the buffer and returns a
non-nil value.
This command makes buffer-or-name appear in some window, without selecting the window or making the buffer current. The argument buffer-or-name must be a buffer or the name of an existing buffer. The return value is the window chosen to display the buffer.
The optional argument action, if
non-nil, should normally be a display action
(described above). display-buffer builds a list
of action functions and an action alist, by consolidating
display actions from the following sources (in order):
display-buffer-overriding-action.display-buffer-alist.display-buffer-base-action.display-buffer-fallback-action.Each action function is called in turn, passing the buffer
as the first argument and the combined action alist as the
second argument, until one of the functions returns
non-nil. The caller can pass
(allow-no-window . t) as an element of the
action alist to indicate its readiness to handle the case of
not displaying the buffer in a window.
The argument action can also have a
non-nil, non-list value. This has the special
meaning that the buffer should be displayed in a window other
than the selected one, even if the selected window is already
displaying it. If called interactively with a prefix
argument, action is t.
The optional argument frame, if
non-nil, specifies which frames to check when
deciding whether the buffer is already displayed. It is
equivalent to adding an element (reusable-frames .
frame) to the action alist of
action. See Display
Action Functions.
The value of this variable should be a display action,
which is treated with the highest priority by
display-buffer. The default value is empty,
i.e., (nil . nil).
The value of this option is an alist mapping conditions to
display actions. Each condition may be either a regular
expression matching a buffer name or a function that takes
two arguments: a buffer name and the action
argument passed to display-buffer. If the name
of the buffer passed to display-buffer either
matches a regular expression in this alist or the function
specified by a condition returns non-nil, then
display-buffer uses the corresponding display
action to display the buffer.
The value of this option should be a display action. This
option can be used to define a standard display action for
calls to display-buffer.
This display action specifies the fallback behavior for
display-buffer if no other display actions are
given.
Next: Display Action Functions, Previous: Switching Buffers, Up: Windows [Contents][Index]